From 6df8bf7dde71fe00ade729a36d8bdcd27dd1c188 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 12 May 2020 07:49:07 -0400 Subject: [PATCH] docs: Updates to the migration guide Remove some duplicated content, reorder things to make more sense, and tweak the wording. --- docs/reference/gtk/migrating-3to4.xml | 556 ++++++++++++-------------- 1 file changed, 245 insertions(+), 311 deletions(-) diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml index ee5bc5ecf9..fb6a19740d 100644 --- a/docs/reference/gtk/migrating-3to4.xml +++ b/docs/reference/gtk/migrating-3to4.xml @@ -80,38 +80,52 @@ GTK 4 removes the GDK_WA_CURSOR flag. Instead, just use gdk_window_set_cursor() to set a cursor on the window after - creating it. - - - GTK 4 also removes the GDK_WA_VISUAL flag, and always uses - an RGBA visual for windows. To prepare your code for this, use + creating it. GTK 4 also removes the GDK_WA_VISUAL flag, and + always uses an RGBA visual for windows. To prepare your code + for this, use gdk_window_set_visual (gdk_screen_get_rgba_visual ()) after creating your window. - - GTK 4 also removes the GDK_WA_WMCLASS flag. If you need this X11-specific functionality, use XSetClassHint() directly.
- Stop using non-RGBA visuals + Stop using direct access to GdkEvent structs - GTK 4 always uses RGBA visuals for its windows; you should make - sure that your code works with that. + In GTK 4, event structs are opaque and immutable. Many fields already + have accessors in GTK 3, and you should use those to reduce the amount + of porting work you have to do at the time of the switch. +
+ +
+ Stop using gdk_pointer_warp() - At the same time, you should stop using GdkVisual APIs, this object - not longer exist in GTK 4. Most of its APIs are deprecated already - and not useful when dealing with RGBA visuals. + Warping the pointer is disorienting and unfriendly to users. + GTK 4 does not support it. In special circumstances (such as when + implementing remote connection UIs) it can be necessary to + warp the pointer; in this case, use platform APIs such as + XWarpPointer() directly.
- Stop using GtkBox:padding, GtkBox:fill and GtkBox:expand + Stop using non-RGBA visuals - GTK 4 removes these #GtkBox child properties, so you should not use them. - You can replace GtkBox:padding using the #GtkWidget:margin properties + GTK 4 always uses RGBA visuals for its windows; you should make + sure that your code works with such visuals. At the same time, + you should stop using GdkVisual APIs, since this object not longer + exists in GTK 4. Most of its APIs are deprecated already and not + useful when dealing with RGBA visuals. + +
+ +
+ Stop using GtkBox padding, fill and expand child properties + + GTK 4 removes these #GtkBox child properties, so you should stop using + them. You can replace GtkBox:padding using the #GtkWidget:margin properties on your #GtkBox child widgets. @@ -152,8 +166,9 @@
Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface() - These functions are not supported in GTK 4. Instead, either use backend-specific - APIs, or render your widgets using #GtkWidgetClass.snapshot(). + These functions are not supported in GTK 4. Instead, either use + backend-specific APIs, or render your widgets using + #GtkWidgetClass.snapshot() (once you are using GTK 4).
@@ -165,7 +180,7 @@ not supported in GTK 4. Instead, you can just pack a GtkImage inside a GtkButton, and control its visibility like you would for any other widget. If you only want to add a named icon to a GtkButton, you can - use gtk_button_set_icon_name(). + use gtk_button_new_from_icon_name().
@@ -180,12 +195,11 @@
Set a proper application ID - In GTK 4 we want the application's #GApplication - 'application-id' (and therefore the D-Bus name), the desktop - file basename and Wayland's xdg-shell app_id to match. In - order to achieve this with GTK 3.x call g_set_prgname() with the same - application ID you passed to #GtkApplication. Rename your - desktop files to match the application ID if needed. + In GTK 4 we want the application's #GApplication 'application-id' + (and therefore the D-Bus name), the desktop file basename and Wayland's + xdg-shell app_id to match. In order to achieve this with GTK 3.x call + g_set_prgname() with the same application ID you passed to #GtkApplication. + Rename your desktop files to match the application ID if needed. The call to g_set_prgname() can be removed once you fully migrated @@ -203,21 +217,19 @@ Stop using gtk_main() and related APIs - GTK4 removes the gtk_main_ family of APIs. The recommended replacement + GTK 4 removes the gtk_main_ family of APIs. The recommended replacement is GtkApplication, but you can also iterate the GLib mainloop directly, - using GMainContext APIs. - - - The replacement for gtk_events_pending() is g_main_context_pending(), - the replacement for gtk_main_iteration() is g_main_context_iteration(). + using GMainContext APIs. The replacement for gtk_events_pending() is + g_main_context_pending(), the replacement for gtk_main_iteration() is + g_main_context_iteration().
Reduce the use of gtk_widget_destroy() - GTK4 introduces a gtk_window_destroy() api. While that is not available - in GTK3, you can prepare for the switch by using gtk_widget_destroy() + GTK 4 introduces a gtk_window_destroy() api. While that is not available + in GTK 3, you can prepare for the switch by using gtk_widget_destroy() only on toplevel windows, and replace all other uses with gtk_container_remove() or g_object_unref(). @@ -226,8 +238,8 @@
Reduce the use of generic container APIs - GTK4 removes gtk_container_add() and gtk_container_remove(). While there - is not always a replacement for gtk_container_remove() in GTK3, you can + GTK 4 removes gtk_container_add() and gtk_container_remove(). While there + is not always a replacement for gtk_container_remove() in GTK 3, you can replace many uses of gtk_container_add() with equivalent container-specific APIs such as gtk_box_pack_start() or gtk_grid_attach(), and thereby reduce the amount of work you have to do at the time of the switch. @@ -245,17 +257,6 @@ have been either impossible or impractical. -
- Convert your ui files - - - A number of the changes outlined below affect .ui files. The - gtk4-builder-tool simplify command can perform many of the - necessary changes automatically, when called with the --3to4 - option. You should always review the resulting changes. - -
-
Stop using GdkScreen @@ -269,9 +270,8 @@ Stop using the root window The root window is an X11-centric concept that is no longer exposed in the - backend-neutral GDK API. gdk_surface_get_parent() will return %NULL for toplevel - windows. If you need to interact with the X11 root window, you can use - gdk_x11_display_get_xrootwindow() to get its XID. + backend-neutral GDK API. If you need to interact with the X11 root window, + you can use gdk_x11_display_get_xrootwindow() to get its XID.
@@ -297,113 +297,80 @@ GdkWindow has been renamed to GdkSurface. - The gdk_window_new() function has been replaced by a number of more - specialized constructors: gdk_surface_new_toplevel(), gdk_surface_new_popup(), - gdk_surface_new_temp(), gdk_wayland_surface_new_subsurface(). - Use the appropriate ones to create your windows. + In GTK 4, the two roles of a standalone toplevel window and of a popup + that is placed relative to a parent window have been separated out into + two interfaces, #GdkToplevel and #GdkPopup. Surfaces implementing these + interfaces are created with gdk_surface_new_toplevel() and + gdk_surface_new_popup(), respectively, and they are presented on screen + using gdk_toplevel_present() and gdk_popup_present(). The present() + functions take parameters in the form of an auxiliary layout struct, + #GdkPopupLayout or #GdkToplevelLayout. If your code is dealing directly + with surfaces, you may have to change it to call the API in these + interfaces, depending on whether the surface you are dealing with + is a toplevel or a popup. - Native and foreign subwindows are no longer supported. These concepts were - complicating the code and could not be supported across backends. + As part of this reorganization, X11-only concepts such as sticky or + keep-below have been removed. If you need to use them on your X11 windows, + you will have to set the corresponding X11 properties (as specified in the + EWMH) yourself. Subsurfaces are only supported with the Wayland backend, + using gdk_wayland_surface_new_subsurface(). Native and foreign subwindows + are no longer supported. These concepts were complicating the code and + could not be supported across backends. gdk_window_reparent() is no longer available. -
- -
- Adapt to GdkEvent API changes - Direct access to GdkEvent structs is no longer possible in - GTK 4. Some frequently-used fields already had accessors - in GTK 3, and the remaining fields have gained accessors - in GTK 4. - - - GdkEvent is now a strictly read-only type, and you - can no longer change any of its fields, or construct new - events. - -
- -
- Stop using gdk_surface_set_event_compression - - Event compression is now always enabled. If you need to see the uncoalesced - motion history, use gdk_motion_event_get_history() on the latest motion event. - -
- -
- Stop using gdk_pointer_warp() - - Warping the pointer is disorienting and unfriendly to users. - GTK 4 does not support it. In special circumstances (such as when - implementing remote connection UIs) it can be necessary to - warp the pointer; in this case, use platform APIs such as - XWarpPointer() directly. + A number of minor API cleanups have happened in GdkSurface + as well. For example, gdk_surface_input_shape_combine_region() + has been renamed to gdk_surface_set_input_region().
- Stop using grabs + The "iconified" window state has been renamed to "minimized" - GTK 4 no longer provides the gdk_device_grab() or gdk_seat_grab() apis. + The GDK_SURFACE_STATE_ICONIFIED value of the + #GdkSurfaceState enumeration is now %GDK_SURFACE_STATE_MINIMIZED. - If you need to dismiss a popup when the user clicks outside (the most common - use for grabs), you can use the GdkPopup #GdkPopup:autohide property instead. - GtkPopover also has a #GtkPopover:autohide property. + The #GdkWindow functions gdk_window_iconify() + and gdk_window_deiconify() have been renamed to + gdk_toplevel_minimize() and gdk_toplevel_present(), respectively. - If you need to prevent the user from interacting with a window - while a dialog is open, use #GtkWindow:modal on the dialog. + The behavior of the minimization and unminimization operations have + not been changed, and they still require support from the underlying + windowing system.
- Stop using gtk_get_current_... APIs + Adapt to GdkEvent API changes - The function gtk_get_current_event() and its variants have been - replaced by equivalent event controller APIs: - gtk_event_controller_get_current_event(), etc. + Direct access to GdkEvent structs is no longer possible in GTK 4. + GdkEvent is now a strictly read-only type, and you can no longer + change any of its fields, or construct new events. All event fields + have accessors that you will have to use. + + + Event compression is always enabled in GTK 4. If you need to see + the uncoalesced motion history, use gdk_motion_event_get_history() + on the latest motion event.
- Adapt to surface API changes - - In GTK 4, the two roles of a standalone toplevel window - and of a popup that is placed relative to a parent window - have been separated out into two interfaces, #GdkToplevel - and #GdkPopup. - - - Surfaces implementing these interfaces are created with - gdk_surface_new_toplevel() and gdk_surface_new_popup(), - respectively, and they are presented on screen using - gdk_toplevel_present() and gdk_popup_present(). The - present() functions take parameters in the form of an - auxiliary layout struct, #GdkPopupLayout or - #GdkToplevelLayout. - - - If your code is dealing directly with surfaces, you may - have to change it to call the API in these interfaces, - depending on whether the surface you are dealing with - is a toplevel or a popup. - + Stop using grabs - As part of this reorganization, X11-only concepts such - as sticky or keep-below have been removed. If you need - to use them on your X11 windows, you will have to set - the corresponding X11 properties (as specified in the - EWMH) yourself. - - - A number of minor API cleanups have happened in GdkSurface - as well. For example, gdk_surface_input_shape_combine_region() - has been renamed to gdk_surface_set_input_region(). + GTK 4 no longer provides the gdk_device_grab() or gdk_seat_grab() + apis. If you need to dismiss a popup when the user clicks outside + (the most common use for grabs), you can use the GdkPopup + #GdkPopup:autohide property instead. GtkPopover also has a + #GtkPopover:autohide property for this. If you need to prevent + the user from interacting with a window while a dialog is open, + use the #GtkWindow:modal property of the dialog.
@@ -418,13 +385,13 @@ Any APIs that deal with global (or root) coordinates have been - removed in GTK4, since not all backends support them. You should + removed in GTK 4, since not all backends support them. You should replace your use of such APIs with surface-relative equivalents. Examples of this are gdk_surface_get_origin(), gdk_surface_move() or gdk_event_get_root_coords().
- +
Adapt to GdkKeymap API changes @@ -435,15 +402,14 @@ on the #GdkDevice representing the keyboard: #GdkDevice:direction, #GdkDevice:has-bidi-layouts, #GdkDevice:caps-lock-state, #GdkDevice:num-lock-state, #GdkDevice:scroll-lock-state and - #GdkDevice:modifier-state. - To obtain the keyboard device, you can use + #GdkDevice:modifier-state. To obtain the keyboard device, you can use gdk_seat_get_keyboard (gdk_display_get_default_seat (display)). If you need access to translated keys for event handling, #GdkEvent now includes all of the translated key state, including consumed modifiers, group and shift level, so there should be no need to - do manually call gdk_keymap_translate_keyboard_state() (which has + manually call gdk_keymap_translate_keyboard_state() (which has been removed). @@ -454,21 +420,6 @@
-
- Adapt to event controller API changes - - A few changes to the event controller and #GtkGesture APIs - did not make it back to GTK3, and have to be taken into account - when moving to GTK4. One is that the - #GtkEventControllerMotion::enter, - #GtkEventControllerMotion::leave, - #GtkEventControllerKey::focus-in and - #GtkEventControllerKey::focus-out signals - have gained new arguments. Another is that #GtkGestureMultiPress - has been renamed to #GtkGestureClick. - -
-
Adapt to changes in keyboard modifier handling @@ -501,6 +452,39 @@
+
+ Stop using gtk_get_current_... APIs + + The function gtk_get_current_event() and its variants have been + replaced by equivalent event controller APIs: + gtk_event_controller_get_current_event(), etc. + +
+ +
+ Convert your ui files + + + A number of the changes outlined below affect .ui files. The + gtk4-builder-tool simplify command can perform many of the + necessary changes automatically, when called with the --3to4 + option. You should always review the resulting changes. + +
+ +
+ Adapt to event controller API changes + + A few changes to the event controller and #GtkGesture APIs + did not make it back to GTK 3, and have to be taken into account + when moving to GTK 4. One is that the #GtkEventControllerMotion::enter + and #GtkEventControllerMotion::leave signals have gained new arguments. + Another is that #GtkGestureMultiPress has been renamed to #GtkGestureClick, + and has lost its area property. A #GtkEventControllerFocus has been + split off from #GtkEventcontrollerKey. + +
+
Focus handling changes @@ -509,17 +493,15 @@ accept keyboard input, but its children still might (in the case of containers). In GTK 4, if :can-focus is %FALSE, the focus cannot enter the widget or any of its descendents, and the default value has changed - from %FALSE to %TRUE. - - - The recommended way to influence focus behavior of custom widgets - in GTK 4 is to override the focus() and grab_focus() vfuncs. + from %FALSE to %TRUE. In addition, there is a #GtkWidget:focusable + property, which controls whether an individual widget can receive + the input focus. The feature to automatically keep the focus widget scrolled into view - with gtk_container_set_focus_vadjustment() has been removed from - GtkContainer, and is provided by scrollables instead. In the common case - that the scrollable is a #GtkViewport, use #GtkViewport:scroll-to-focus. + with gtk_container_set_focus_vadjustment() has been removed together with + GtkContainer, and is provided by scrollable widgets instead. In the common + case that the scrollable is a #GtkViewport, use #GtkViewport:scroll-to-focus.
@@ -541,8 +523,8 @@
Adapt to GtkBox API changes - GtkBox no longer has pack-start and -end. Pack your widgets in the - correct order, or reorder them as necessary. + The GtkBox pack-start and -end methods have been replaced by gtk_box_prepend() + and gtk_box_append(). You can also reorder box children as necessary.
@@ -550,8 +532,8 @@ Adapt to GtkHeaderBar and GtkActionBar API changes The gtk_header_bar_set_show_close_button() function has been renamed to - the more accurate name gtk_header_bar_set_show_title_buttons(). The corresponding - getter and the property itself have also been renamed. + the more accurate name gtk_header_bar_set_show_title_buttons(). The + corresponding getter and the property itself have also been renamed. The ::pack-type child properties of GtkHeaderBar and GtkActionBar have @@ -586,8 +568,11 @@ The abstract base class GtkBin for single-child containers has been removed. The former subclasses are now derived directly from GtkWidget, - and have a "child" property for their child widget. The affected classes - are: + and have a "child" property for their child widget. To add a child, use + the setter for the "child" property (e.g. gtk_frame_set_child()) instead + of gtk_container_add(). Adding a child in a ui file with + child still works. + The affected classes are: GtkAspectFrame @@ -605,19 +590,30 @@ GtkWindow (and subclasses) - To add a child, use the setter for the "child" property (e.g. - gtk_frame_set_child()) instead of gtk_container_add(). Adding a child - in a ui file with child still works. + If you have custom widgets that were derived from GtkBin, you should + port them to derive from GtkWidget. Notable vfuncs that you will have + to implement include dispose() (to unparent your child), compute_expand() + (if you want your container to propagate expand flags) and + get_request_mode() (if you want your container to support height-for-width. + + + You may also want to implement the GtkBuildable interface, to support + adding children with child in ui files.
Adapt to GtkContainer removal - The abstract bas class GtkContainer for general containers has been + The abstract base class GtkContainer for general containers has been removed. The former subclasses are now derived directly from GtkWidget, - and have class-specific add and remove functions. The affected classes - are: + and have class-specific add() and remove() functions. + The most noticable change is the use of gtk_box_append() or gtk_box_prepend() + instead of gtk_container_add() for adding children to GtkBox, and the change + to use container-specific remove functions, such as gtk_stack_remove() instead + of gtk_container_remove(). Adding a child in a ui file with + child still works. + The affected classes are: GtkActionBar @@ -637,11 +633,22 @@ GtkTreeView - The most noticable change will be to use gtk_box_append() or gtk_box_prepend() - instead of gtk_container_add() for adding children to GtkBox, and the change - to use container-specific remove functions, such as gtk_stack_remove() instead - of gtk_container_remove(). Adding a child in a ui file with - child still works. + Without GtkContainer, there are no longer facilities for defining and + using child properties. If you have custom widgets using child properties, + they will have to be converted either to layout properties provided + by a layout manager (if they are layout-related), or handled in some + other way. One possibility is to use child meta objects, as seen with + GtkAssistantPage, GtkStackPage and the like. + +
+ +
+ Stop using GtkContainer::border-width + + GTK 4 has removed the #GtkContainer::border-width property (together + with the rest of GtkContainer). Use other means to influence the spacing + of your containers, such as the CSS margin and padding properties on child + widgets.
@@ -677,22 +684,10 @@
Adapt to GtkCssProvider API changes - In GTK 4, the various #GtkCssProvider load functions have lost - their #GError argument. If you want to handle CSS loading errors, - use the #GtkCssProvider::parsing-error signal instead. - - - gtk_css_provider_get_named() has been replaced by - gtk_css_provider_load_named(). - -
- -
- Stop using GtkContainer::border-width - - GTK 4 has removed the #GtkContainer::border-width property. - Use other means to influence the spacing of your containers, - such as the CSS margin and padding properties on child widgets. + In GTK 4, the various #GtkCssProvider load functions have lost their + #GError argument. If you want to handle CSS loading errors, use the + #GtkCssProvider::parsing-error signal instead. gtk_css_provider_get_named() + has been replaced by gtk_css_provider_load_named().
@@ -714,28 +709,33 @@ implement size requisition, namely the gtk_widget_get_preferred_width() family of functions. To simplify widget implementations, GTK 4 uses only one virtual function, GtkWidgetClass::measure() that widgets - have to implement. + have to implement. gtk_widget_measure() replaces the various + gtk_widget_get_preferred_ functions for querying sizes.
Adapt to GtkWidget's size allocation changes - The #GtkWidget::size-allocate signal now takes the baseline as an - argument, so you no longer need to call gtk_widget_get_allocated_baseline() + The #GtkWidget.size_allocate() vfunc takes the baseline as an argument + now, so you no longer need to call gtk_widget_get_allocated_baseline() to get it. + + The ::size-allocate signal has been removed, since it is easy + to misuse. If you need to learn about sizing changes of custom + drawing widgets, use the #GtkDrawingArea::resize or #GtkGLArea::resize + signals. +
Switch to GtkWidget's children APIs - Instead of the GtkContainer subclass, in GTK 4, any widget can - have children, and there is new API to navigate the widget tree: - gtk_widget_get_first_child(), gtk_widget_get_last_child(), + In GTK 4, any widget can have children (and GtkContainer is gone). + There is new API to navigate the widget tree, for use in widget + implementations: gtk_widget_get_first_child(), gtk_widget_get_last_child(), gtk_widget_get_next_sibling(), gtk_widget_get_prev_sibling(). - The GtkContainer API still works, but if you are implementing - your own widgets, you should consider using the new APIs.
@@ -757,18 +757,17 @@
- Don't use -gtk-outline-...-radius in your CSS + Don't use -gtk-icon-theme in your CSS - These non-standard properties have been removed from GTK - CSS. Just use regular border radius. + GTK now uses the current icon theme, without a way to change this.
- Use gtk_widget_measure + Don't use -gtk-outline-...-radius in your CSS - gtk_widget_measure() replaces the various gtk_widget_get_preferred_ functions - for querying sizes. + These non-standard properties have been removed from GTK + CSS. Just use regular border radius.
@@ -809,6 +808,8 @@ The default value of #GtkWidget:visible in GTK 4 is %TRUE, so you no longer need to explicitly show all your widgets. On the flip side, you need to hide widgets that are not meant to be visible from the start. + The only widgets that still need to be explicitly shown are toplevel + windows, dialogs and popovers. A convenient way to remove unnecessary property assignments like this @@ -817,7 +818,8 @@ The function gtk_widget_show_all(), the #GtkWidget:no-show-all property - and its getter and setter have been removed in GTK 4, so you should stop using them. + and its getter and setter have been removed in GTK 4, so you should stop + using them. @@ -848,11 +850,8 @@ A number of #GdkPixbuf-based APIs have been removed. The available replacements are either using #GIcon, or the newly introduced #GdkTexture or #GdkPaintable - classes instead. - - - If you are dealing with pixbufs, you can use gdk_texture_new_for_pixbuf() - to convert them to texture objects where needed. + classes instead. If you are dealing with pixbufs, you can use + gdk_texture_new_for_pixbuf() to convert them to texture objects where needed. @@ -878,7 +877,9 @@ Stop using GtkWidget::draw The #GtkWidget::draw signal has been removed. Widgets need to implement the - #GtkWidgetClass.snapshot() function now. Connecting draw signal handlers is no longer possible. + #GtkWidgetClass.snapshot() function now. Connecting draw signal handlers is + no longer possible. If you want to keep using cairo for drawing, use + gtk_snaphot_append_cairo(). @@ -926,24 +927,15 @@ to override the icon size. - The ::stock-size property of GtkCellRendererPixbuf has been renamed to + The :stock-size property of GtkCellRendererPixbuf has been renamed to #GtkCellRendererPixbuf:icon-size. -
- Convert .ui files - - The simplify command of gtk4-builder-tool has gained a --3to4 option, which - can help with some of the required changes in .ui files, such as converting - child properties to child meta objects. - -
-
Adapt to changes in the GtkAssistant API - The ::has-padding property is gone, and GtkAssistant no longer adds padding + The :has-padding property is gone, and GtkAssistant no longer adds padding to pages. You can easily do that yourself.
@@ -969,8 +961,8 @@
Adapt to changes in GtkOverlay API - The GtkOverlay::pass-through child property has been replaced by the - GtkWidget::can-target property. Note that they have the opposite sense: + The GtkOverlay :pass-through child property has been replaced by the + #GtkWidget:can-target property. Note that they have the opposite sense: pass-through == !can-target.
@@ -995,37 +987,15 @@ -
- Stop using child properties - - GtkContainer no longer provides facilities for defining and using - child properties. If you have custom widgets using child properties, - they will have to be converted either to layout properties provided - by a layout manager (if they are layout-related), or handled in - some other way. One possibility is to use child meta objects, - as seen with GtkAssistantPage, GtkStackPage and the like. - -
- -
- Stop using gtk_menu_set_display() - - This function has been removed. Menus should always be - attached to a widget and get their display that way. - -
-
Stop using gtk_window_activate_default() The handling of default widgets has been changed, and activating the default now works by calling gtk_widget_activate_default() - on the widget that caused the activation. - - - If you have a custom widget that wants to override the default - handling, you can provide an implementation of the default.activate - action in your widgets' action groups. + on the widget that caused the activation. If you have a custom widget + that wants to override the default handling, you can provide an + implementation of the default.activate action in your widgets' action + groups.
@@ -1042,7 +1012,7 @@
Stop using the GtkWidget::display-changed signal - To track the current display, use the GtkWidget::root property + To track the current display, use the #GtkWidget::root property instead.
@@ -1097,29 +1067,6 @@ -
- The "iconified" window state has been renamed to "minimized" - - The GDK_SURFACE_STATE_ICONIFIED value of the - #GdkSurfaceState enumeration is now %GDK_SURFACE_STATE_MINIMIZED. - - - The #GdkSurface functions gdk_surface_iconify() - and gdk_surface_deiconify() have been renamed to - gdk_toplevel_minimize() and gdk_toplevel_present(), respectively. - - - The corresponding #GtkWindow functions gtk_window_iconify() - and gtk_window_deiconify() have been renamed - to gtk_window_minimize() and gtk_window_unminimize(), respectively. - - - The behavior of the minimization and unminimization operations have - not been changed, and they still require support from the underlying - windowing system. - -
-
GtkMenu, GtkMenuBar and GtkMenuItem are gone @@ -1139,7 +1086,6 @@ complex layout in menu-like popups, consider directly using a #GtkPopover instead. - Since menus are gone, GtkMenuButton also lost its ability to show menus, and needs to be used with popovers in GTK 4. @@ -1150,10 +1096,8 @@ GtkToolbar has been removed Toolbars were using outdated concepts such as requiring special toolitem - widgets. - - - Toolbars should be replaced by using a GtkBox with regular widgets instead. + widgets. Toolbars should be replaced by using a GtkBox with regular widgets + instead and the "toolbar" style class.
@@ -1177,46 +1121,36 @@
- Switch to the new DND api - - The source-side DND apis in GTK 4 have been changed to use an event controller, #GtkDragSource. - - - Instead of calling gtk_drag_source_set() and connecting to #GtkWidget signals, you create - a #GtkDragSource object, attach it to the widget with gtk_widget_add_controller(), and connect - to #GtkDragSource signals. Instead of calling gtk_drag_begin() on a widget to start a drag - manually, call gdk_drag_begin(). - + Switch to the new Drag-and-Drop api - The ::drag-data-get signal has been replaced by the #GtkDragSource::prepare signal, which - returns a #GdkContentProvider for the drag operation. + The source-side Drag-and-Drop apis in GTK 4 have been changed to use an event + controller, #GtkDragSource. Instead of calling gtk_drag_source_set() + and connecting to #GtkWidget signals, you create a #GtkDragSource object, + attach it to the widget with gtk_widget_add_controller(), and connect + to #GtkDragSource signals. Instead of calling gtk_drag_begin() on a widget + to start a drag manually, call gdk_drag_begin(). + The ::drag-data-get signal has been replaced by the #GtkDragSource::prepare + signal, which returns a #GdkContentProvider for the drag operation. - The destination-side DND apis in GTK 4 have also been changed to use and event controller, - #GtkDropTarget. - - - Instead of calling gtk_drag_dest_set() and connecting to #GtkWidget signals, you create - a #GtkDropTarget object, attach it to the widget with gtk_widget_add_controller(), and - connect to #GtkDropTarget signals. - - - The ::drag-motion signal has been renamed to #GtkDropTarget::accept, and instead of - ::drag-data-received, you need to use async read methods on the #GdkDrop object, such - as gdk_drop_read_async() or gdk_drop_read_value_async(). + The destination-side Drag-and-Drop apis in GTK 4 have also been changed + to use an event controller, #GtkDropTarget. Instead of calling + gtk_drag_dest_set() and connecting to #GtkWidget signals, you create + a #GtkDropTarget object, attach it to the widget with + gtk_widget_add_controller(), and connect to #GtkDropTarget signals. + The ::drag-motion signal has been renamed to #GtkDropTarget::accept, and + instead of ::drag-data-received, you need to use async read methods on the + #GdkDrop object, such as gdk_drop_read_async() or gdk_drop_read_value_async().
Adapt to GtkIconTheme API changes - gtk_icon_theme_lookup_icon() returns a #GtkIconPaintable - object now, instead of a #GtkIconInfo. It always returns - a paintable in the requested size, and never fails. - - - A number of no-longer-relevant lookup flags and API - variants have been removed. + gtk_icon_theme_lookup_icon() returns a #GtkIconPaintable object now, instead + of a #GtkIconInfo. It always returns a paintable in the requested size, and + never fails. A number of no-longer-relevant lookup flags and API variants + have been removed.
-- 2.30.2